We've had a series of articles aimed at programmers who want to release software to the public. Such software should be as professional as possible, and an important part of that goal is an excellent user's guide or help file.

Previous Articles on Help Files

The newsletter contains many articles on help file creation. Download the zipped versions of the following issues to get all of the necessary files. Most of the articles address the mechanics of creating help files in various formats, but one tells you how to write the helpfile. Pay particular attention to Jerry Muelver's article in issue #105. It tells you how to outline and construct your help file.

• Helpfile Creation and Use. Issue #75
• Liberty Basic Simple Help, by Tom Nally. Issue #103.
• Help (... is on the way!), by Jerry Muelver. Issue #105.
• Creating Compiled HTML Help, by Alyce Watson. Issue #108.
• Rich Text Format Help, by Jim Brossman. Issue #115.
• A Few Thoughts On Cross-Platform Help, by Tom Nally. Issue #115.
• Liberty Basic Simple Help Version 2, by Tom Nally. Issue #120.
• Bitmap Help - A Simple Help Engine, by Tom Nally. Issue #125.
• Advanced HTML Help Workshop Use: Adding Context Sensitive Help to Your LB Programs, by Dennis McKinney. Issue #131

Why are you writing?

If you are writing to tell the reader how to use your software, you'll want to use plain language. The use of complicated sentences, big words, and lots of jargon do not help your reader understand either your writing or your software!

How to Write Well

It's easy to write well, if you take it one step at a time. Any written article is composed of these parts:

• words
• phrases
• sentences
• paragraphs
• document design

Words

Plain language writing emphasizes the use of the clearest words possible to describe the subject. I cannot stress this enough: Use short, simple, familiar, everyday words!

Use simple, familiar words instead of jargon, unfamiliar words, or long, complex words. Some examples follow. Use the second word in each pair, instead of the first one.

• utilize -> use
• accomplish -> do
• endeavor -> try
• locality -> place
• facilitate -> help
• optimum -> best

Sometimes, two or more simple words are better than a single complex word. Replace the complex words in the following list with the simple phrase that means the same thing.

• disseminate -> send out
• expedite -> speed up
• formulate -> work out

Try to avoid technical words. If you must use a technical term, either define it, explain it, or give an example. Here is an example of a technical term that is explained:

Phrases

Don't include a lot of unncessary words! Keep things simple and short so that your readers can understand them easily. In the following list, replace the wordy phrase with the simple word or phrase that follows.

• with regard to -> about
• by means of -> by
• in the event that -> if
• until such time -> until
• subsequent to -> after
• an adequate number of -> enough
• an excessive number of -> too many

To facilitate optimum results in technical writing, endeavor to utilize uncomplicated phraseology. OOPS! That sentence should be: To help you get the best results in technical writing, try to use simple language.

Sentences

Use clear, simple sentences. Your readers find it easiest to understand simple, declarative sentences. Sentences that are long and contain many phrases and clauses may cause readability problems. Try to keep sentences short -- about 15 words per sentence.

Paragraphs

In general, a paragraph should contain only one idea unless you are linking related points. It is much easier for your readers to understand this way. Large, dense blocks of text are also difficult to understand. The best paragraphs are no more than four or five sentences long.

Document Design

Leave space between paragraphs for the best readability. Divide your documents into sections of related information, as Jerry discussed in issue #105. Helpfiles should be divided into topics, and each topic should follow the rules discussed above. The number and types of topics will vary according to the software, of course.

Style

Technical writing can be as formal or informal as you like. A little humor is allowed! Just be sure that your style of writing matches the style of the software. Never, ever talk down to your users. Treat them as respected colleagues.

Spelling

Spelling counts! Use a spell checker. If you do not have an editor with a built-in spell checker, you can download WordWeb free, here:

[http://wordweb.info/free/]

Proof-reading

When you think you are finished, put your document aside for a few days. Read it again with fresh eyes. Does it still make sense? Do any errors jump out at you? Even better, ask another person to read it for you and report back. Also, be sure to distribute your user's guide along with test versions of your program, and ask your testers to comment on it, as well.